home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / uds200.zip / UDS200.DOC < prev    next >
Text File  |  1991-04-26  |  24KB  |  492 lines
  1.  
  2.                     UDS: The User Description System
  3.                          Version 2.00f for Fido*
  4.          Copyright (c) 1991 by Lester B. Kooyman (1:204/501.0)
  5.                        for Caffeine-Free Software
  6.                  (Portions copyright by Allan P. Hurst)
  7.                         Documentation by PC Bear
  8.              Documentation (c) 1991 Caffeine-Free Software
  9.  
  10. (*Fido, FidoNet, and the dog-with-diskette are trademarks of Tom Jennings
  11. and Fido Software, without whom none of this would be possible. Thanks, TJ!
  12. I would also like to thank Bob Hartman and Vince Perriello for writing
  13. BinkleyTerm and making it available. Tip o' the hat also to Ray Gwinn for
  14. his excellent X00 FOSSIL driver. Also thanks to Wynn Wagner III, who
  15. originated Opus, and set the groundwork upon which BinkleyTerm and other
  16. programs have been built. Without the work of these fine people [and others
  17. I have inadvertently forgotten to mention], the FidoNet software environment
  18. would not be what it is today - a sophisticated and cheap BBS and email
  19. standard for the world. Also many thanks to Yoshi for writing LHARC!)
  20.  
  21. (Intel is probably still claiming trademark on the names of their CPU
  22. processor family. At this writing, the name "386" has been held in a
  23. court of law to not be a trademark. Personally, I recommend purchasing
  24. processors from any vendor *other than Intel* and thus helping to break
  25. the monopolistic stranglehold Intel has on the PC industry. AMD makes
  26. excellent processors, for example. Harris and others manufacture versions
  27. of the 286, and AMD has just introduced versions of the 386. Even an IBM
  28. version of an Intel processor will help to break the monopoly, but probably
  29. doesn't send the message that purchasing an AMD product does. Vote with
  30. your dollars! Down with monopolies! Up with competition! This has been
  31. a paid political announcement.)
  32.  
  33. ===============================================================================
  34.  
  35. 0. Packing List
  36. ---------------
  37.  
  38. The archive UDS200.LZH should contain the following files:
  39.  
  40.   READ.ME (a very small plea)
  41.   UDS.286
  42.   UDS.EXE
  43.   UDSMAINT.286
  44.   UDSMAINT.EXE
  45.   UDSUPDT.286
  46.   UDSUPDT.EXE
  47.   UDS200.DOC (this file)
  48.  
  49. The versions of the programs ending in ".EXE" are generic and should run
  50. on all 8088, 8086, 80186, 80286, 80386 or 80486 systems. It should run
  51. on the 80786 when Intel gets there. This assumes Intel continues to
  52. maintain object-code compatibility in the 80X86 processor family, a safe
  53. bet.
  54.  
  55. The versions of the programs ending in ".286" have been compiled with
  56. an option to optimize for the 80286 and higher processors. Machine
  57. instructions specific to the 286 have been used. These versions of the
  58. programs will *not* run on the 8088, 8086 or 80186 processors, but should
  59. provide somewhat better performance on 80286 and higher processors (this
  60. includes the 386). Users of 286, 386, or 486 CPUs should erase the
  61. versions ending in ".EXE" and rename the versions ending in ".286" to
  62. replace them. Keep your original archive for backup!
  63.  
  64. ===============================================================================
  65.  
  66. 1. What it is, etc., other introductory drivel.
  67. -----------------------------------------------
  68.  
  69. The User Description System (hereafter referred to as "UDS" or "the UDS"
  70. but never as "Mr. UDS to you") is designed to add a user description
  71. database to the Fido BBS system. The UDS runs as an outside program from
  72. Fido.
  73.  
  74. To run the UDS, you should be running the FOSSIL version of Fido. Although
  75. the UDS has only been tested with Ray Gwinn's fine X00 software, it uses
  76. general FOSSIL calls and should work with other FOSSIL drivers such as
  77. BNU and OPUSCOMM. While I cannot promise I will be able to respond to
  78. support queries with drivers other than X00, if you netmail me the FOSSIL
  79. you are using (along with its documentation) and a description of problems
  80. you are experiencing, I will investigate to the limits of my time and
  81. ability. Transcriptions of error messages or screen prints would be very
  82. helpful, along with a description of your hardware and software environment.
  83. Priority will be given to problems reported by those who have read and
  84. responded to the small plea in READ.ME.
  85.  
  86. The UDS consists of three programs: UDS.EXE, UDSUPDT.EXE, and UDSMAINT.EXE.
  87. Their functions are as follows -
  88.  
  89.         UDS.EXE:        The User Description System itself. Allows users to
  90.                         search and display descriptions of other users
  91.                         as well as create, delete, and modify their own
  92.                         descriptions.
  93.  
  94.         UDSUPDT.EXE:    A program to update the dates that users last called
  95.                         the BBS, as held in their user description file
  96.                         entries. Should be run no less often than daily.
  97.  
  98.         UDSMAINT.EXE:   A program to provide two less-frequently-needed
  99.                         functions; to remove duplicate descriptions for
  100.                         users who somehow end up with more than one
  101.                         (this is unlikely at this "advanced" stage of
  102.                         development of the UDS), and to delete the
  103.                         descriptions of users who no longer appear in
  104.                         your CALLER.SYS file. In other words, if you run
  105.                         UDSMAINT after stamping and purging the records
  106.                         of users who have not called your BBS in some
  107.                         time, you will effectively delete them from the
  108.                         UDS as well.
  109.  
  110. ===============================================================================
  111.  
  112. 2. How to run the programs
  113. --------------------------
  114.  
  115. a.) UDS.EXE
  116. -----------
  117.  
  118. This program creates and maintains a file named USERDESC.DAT. The first
  119. time a description is entered by a user, UDS will create USERDESC.DAT if
  120. it does not exist.
  121.  
  122. The command line to run the UDS is:
  123.  
  124. UDS /# [/REBOOT|/END] {/SHARE /UDSPATH=path /CALLERPATH=path /FIDOPATH=path}
  125.  
  126. where:
  127.  
  128.       /#               is a FOSSIL port number in the range of 0-7
  129.       /REBOOT          indicates to terminate with reboot upon
  130.                          carrier loss (controlled by the FOSSIL)
  131.       /END             indicates to simply end the program upon carrier loss,
  132.                          setting the DOS errorlevel prior to exit
  133.       /SHARE           indicates DOS file sharing/record locking support
  134.                          is active and should be used.
  135.       /UDSPATH=path    is the path to be used to open USERDESC.DAT
  136.       /CALLERPATH=path is the path to be used to open CALLER.SYS
  137.       /FIDOPATH=path   is the path to be used to open FIDO.SYS
  138.  
  139.       Parameters between "{" and "}" are optional
  140.       Parameters between "[" and "]" are mandatory, one and only one
  141.        must be chosen from the selections separated by "|"
  142.  
  143.       The parameters are case-insensitive. "/REBOOT" is the same to the
  144.       program as "/reboot".
  145.  
  146. /#:
  147. --
  148.  
  149. Note that the FOSSIL port number argument is positional and mandatory
  150. (it must be the first argument specified on the command line). The UDS
  151. uses the same port numbering scheme as X00. That is, port 0 is the first
  152. FOSSIL port, and port 7 is the highest port. Whatever number is used will
  153. be passed on to the FOSSIL directly. Fido numbers ports in a slightly
  154. different fashion, i.e., from 1 to 8 rather than 0 to 7. For this reason
  155. you should use the general rule of thumb that the port specified to the
  156. UDS should be one less than the number you specify to Fido. Therefore,
  157. in the most common configuration, with Fido using com1, you would specify
  158. the port to the UDS as 0.
  159.  
  160. [/REBOOT|/END]:
  161. --------------
  162.  
  163. You must choose one or the other of these parameters. If you choose
  164. /reboot, during program initialization the UDS will tell the FOSSIL
  165. to reboot your computer if carrier drops. This is mostly for single-line
  166. Fido installations. It would not be a good idea when running under
  167. DESQview or another multitasker! It also may not function on certain
  168. 386 systems with certain BIOSes (it does not work on my new 386).
  169. In that case, you should use the /end parameter. When the UDS exits
  170. normally back to the batch file that invoked it, the FOSSIL will be
  171. told to no longer reboot if carrier drops.
  172.  
  173. The /end parameter tells the UDS to use its own routines to monitor
  174. the loss of carrier on the line. In most cases this will be much faster
  175. than the /reboot option. The reason it will be faster is that my tests
  176. have shown that the UDS's internal carrier-loss-detect routines react
  177. nearly as quickly as X00's, and you do not need to wait for your system
  178. to reboot. This option is recommended, even for single-line systems.
  179.  
  180. When the UDS exits due to carrier loss, it will set the DOS ERRORLEVEL
  181. to 2. If it exits for any other reason, the DOS ERRORLEVEL will be set
  182. to 1. The following batch file is an example of this. Note that this
  183. batch file may not look exactly like yours, since it is used with my
  184. system, where I run BinkleyTerm and Fido.
  185.  
  186.  
  187.  
  188.     @Echo Off
  189.     :START
  190.       D:
  191.       Cd \FIDO
  192.       goto loop
  193.     :RELOGIN
  194.       relogin
  195.     :LOOP
  196.       E:FIDO %1/O /1 1/I
  197.       if errorlevel 6 goto esp
  198.       if errorlevel 5 goto exit
  199.     :ESP
  200.       uds /0 /end /share /udspath=d:\fido /callerpath=d:\fido /fidopath=d:\fido
  201.       if errorlevel 2 goto exit
  202.       goto relogin
  203.     :EXIT
  204.       modemoff /0
  205.       cd \mail
  206.       Binkley
  207.  
  208. If carrier drops while the caller is in the UDS, the program will exit
  209. with an errorlevel of 2. This batch file will trap that, and branch to
  210. the label :EXIT. At that label I run a quick utility to take the modem
  211. off-hook, and then return to the main batch file which runs BinkleyTerm,
  212. which I call BINKLEY.BAT. Fido had been exited to in the first place with
  213. Binkley's BBSBATCH option. If the program exits normally, the DOS ERRORLEVEL
  214. will be set to 1, and the batch file branches to label :RELOGIN, where
  215. the caller is relogged onto Fido. I downloaded the relogin program from
  216. TJ's bbs, but you can find this program on lots of systems.
  217.  
  218.  
  219. While the /end option senses carrier loss very quickly in my experience,
  220. there is at least one case I have noticed where it may take a few seconds
  221. to notice that carrier has dropped. I have discovered that with high speed
  222. modems (in my case a V32/V42bis 9600bps Practical Peripherals modem) it
  223. can take a few extra seconds.
  224.  
  225.  
  226. /SHARE:
  227. -------
  228.  
  229. This parameter is optional. It is intended for multiline installations.
  230. I am running under DESQview, but this should also work if a LAN is in
  231. use. If you specify /share, you *must* load the DOS program SHARE.EXE
  232. during your system's initialization (probably in your AUTOEXEC.BAT file).
  233. Some versions of DOS have sharing support built in. If your version of
  234. DOS includes SHARE.EXE on its distribution disks, then you should use it
  235. (if you are running a multiline Fido installation). As far as I know,
  236. this means that you should use SHARE.EXE with all versions of Microsoft's
  237. and IBM's DOS from 3.1 through and including 3.3.
  238.  
  239. This parameter actually causes the UDS to do more than open the
  240. USERDESC.DAT file with sharing. When /share is specified, the UDS will
  241. do two things:
  242.  
  243.         - Lock the USERDESC.DAT file during changes. This includes
  244.           description additions, changes and deletions by users while
  245.           online.
  246.  
  247.         - Close and reopen USERDESC.DAT whenever a user executes either
  248.           a search or a list of users' descriptions.
  249.  
  250. There are a couple of consequences of the above. First, no attempt is
  251. made in the program to be graceful if SHARE.EXE (or sharing support) has
  252. not been loaded. If you start the program with /share, and have not loaded
  253. SHARE.EXE, the program will either lock up your computer or exit with an
  254. unexpected error level that will probably cause your system to do unexpected
  255. things. The other consequence is more pleasant. If two users are online in
  256. the UDS, and the caller on line 1 updates his or her description, the
  257. user online on line 2 will see the new or changed description the next
  258. time he or she executes a search or a list. This makes the UDS database
  259. "almost realtime".
  260.  
  261. For those interested in such details, the UDS locks the USERDESC.DAT
  262. file on a record basis rather than locking the entire file. In addition,
  263. the record that is locked is always the first record in the file. This
  264. lock is held only as long as is physically necessary. In other words, all
  265. the preparation for writing or deleting the record is done before the
  266. lock is obtained, then the file activity takes place, and the record is
  267. immediately unlocked. In this way, record 1 of the file serves as a
  268. resource serialization semaphore. It is a way of signalling that the
  269. file is locked for update in a logical rather than a physical fashion.
  270. For this reason, other programs will not necessarily know that the file
  271. is logically locked unless they understand this convention. If you write
  272. additional programs to manipulate the USERDESC.DAT file, you should be
  273. aware of this.
  274.  
  275. /UDSPATH=path:
  276. -------------
  277.  
  278. This is the path where the USERDESC.DAT file lives. It should be specified
  279. without a trailing backslash, like so:
  280.  
  281.                             /udspath=d:\fido
  282.  
  283. It does not need to be the path where Fido is installed.
  284.  
  285. This is an optional parameter. If it is not specified, the UDS will look
  286. for the file USERDESC.DAT in the directory which is current when the program
  287. UDS.EXE is invoked.
  288.  
  289. Please see the section "a note about path options and multiline" which
  290. follows later.
  291.  
  292. /CALLERPATH=path:
  293. ----------------
  294.  
  295. This is the path where CALLER.SYS is located. Like /udspath, it should
  296. be specified without a trailing backslash (putting the trailing backslash
  297. on any of these path options will cause the program to malfunction).
  298.  
  299. Again, this does not need to be the path where Fido is installed. The
  300. default, as in the /udspath option, is to look in the directory which is
  301. current when the program UDS.EXE is invoked, if this optional paramter is
  302. not specified on the command line.
  303.  
  304. Please see the section "a note about path options and multiline" which
  305. follows later.
  306.  
  307. /FIDOPATH=path:
  308. --------------
  309.  
  310. Again, an optional parameter, with the same default logic if not specified.
  311. This is the path where FIDO.SYS is located. It does not need to be the same
  312. path as /callerpath or /udspath, and will probably not be in multiline
  313. installations.
  314.  
  315. Please see the section "a note about path options and multiline" which
  316. follows later.
  317.  
  318.  
  319. A note about path options and Multiline operation:
  320. -------------------------------------------------
  321.  
  322. Although Fido's author has replied that multiline Fido installations may
  323. share FIDO.SYS, the UDS has not been tested in such an environment and
  324. will probably not work if Fido is configured that way. The only way that
  325. the UDS has been tested to work in a multiline Fido configuration is in
  326. a configuration like the following:
  327.  
  328.  
  329.         - One copy of USERDESC.DAT, located where you want it.
  330.  
  331.         - One copy of CALLER.SYS, located most likely in the directory
  332.           where your "main" or first copy of Fido is located.
  333.  
  334.         - One copy of FIDO.SYS *for each line of Fido you are running*
  335.           located in the directories dedicated to each Fido line.
  336.  
  337. In other words, if you are running three lines of Fido, you would have:
  338.  
  339.         - One copy of USERDESC.DAT, shared by all lines.
  340.  
  341.         - One copy of CALLER.SYS, shared by all lines.
  342.  
  343.         - Three copies of FIDO.SYS, in three different subdirectories,
  344.           one for each of the three lines of Fido you are running.
  345.  
  346. In this case, while setting up Fido, you would have run "SET-FIDO" three
  347. times, once in each of the subdirectories dedicated to the three individual
  348. Fido lines you are running. You would have pointed the second and third
  349. copies of Fido to the copy of CALLER.SYS they all share, with the options
  350. in FIDO.INI that are meant for this purpose.
  351.  
  352. The reason that this is necessary is that the UDS reads the FIDO.SYS file
  353. for its line (as specified in the command-line parameter /fidopath) in
  354. order to find the record number of the caller online. The UDS then gets
  355. the caller's record from CALLER.SYS. The path in /callerpath is used to
  356. find the CALLER.SYS file.
  357.  
  358. Theoretically, you could have a separate copy of CALLER.SYS for each line,
  359. as long as you tell Fido (in FIDO.INI for that line) and the UDS (with the
  360. /callerpath parameter) about it. In fact, I have run with this type of
  361. configuration on my own system for a short time. You might wish to do
  362. this, for example, if you provide one free or otherwise unrestricted
  363. telephone line to your system, and other lines that have access requirements
  364. (such as requiring a caller to be a contributor or member of a club or
  365. other organization).
  366.  
  367. ===============================================================================
  368.  
  369. b.) UDSUPDT.EXE
  370. ---------------
  371.  
  372. This program updates the "this user last called on" information in the
  373. file USERDESC.DAT. It should be run at least once a day so that this
  374. information is current. Multiline installations should beware of running
  375. this program while multiple lines are active. I run it during my daily
  376. maintenance event, when all lines other than my main mailer line are
  377. executing wait events. See the READ.ME file included in the UDS200.LZH
  378. distribution archive for information on OFFHOOK.LZH, another fine product
  379. of Caffeine-Free Software, which helps Fido lines to go offhook during
  380. these times while one line executes maintenance-type events. This also
  381. means your callers reach a busy signal rather than a ring-no-answer.
  382.  
  383. If you run UDSUPDT.EXE without any command-line parameters, it will
  384. display the following:
  385.  
  386.  
  387. UDSupdt 2.00f (29Mar91)/(c)1991 Lester B. Kooyman for Caffeine-Free Software
  388.                                                      (Not Coffee-Protected!)
  389.  
  390. Syntax:
  391.        udsupdt /udspath=xxx /fidopath=yyy
  392.   OR:
  393.        udsupdt /current
  394.  
  395. Where: xxx is the path where USERDESC.DAT is found
  396.   and: yyy is the path where CALLER.SYS is found.
  397.    Or: /current means use the current subdirectory for both files.
  398.  
  399. The /udspath and /fidopath parameters are specified under the same rules
  400. as described for UDS.EXE. Don't include a trailing backslash! If you have
  401. USERDESC. DAT and FIDO.SYS installed in the directory which is current
  402. when you run UDSUPDT, you can use the shorter argument /current. One of
  403. these approaches must be used.
  404.  
  405.  
  406. ===============================================================================
  407.  
  408.  
  409. c.) UDSMAINT.EXE
  410. ----------------
  411.  
  412. This program takes no command-line arguments and is unforgiving. It has
  413. no error recovery, so be good to it! Its purpose is twofold: one to
  414. remove multiple descriptions if a user has more than one (should not
  415. occur, happened to me before I got the multiline logic correct), and two
  416. to delete description entries for users who are not found in CALLER.SYS
  417. or who have descriptions which are blank. CALLER.SYS and USERDESC.DAT
  418. must be in the same subdirectory, and this directory must be the current
  419. one when the program is invoked. It does not touch your original input
  420. file, so it is safe to run. The output is in a file called NEWUDS.DAT.
  421.  
  422. This allows you to have second thoughts. You need to erase (or archive
  423. and save) the original USERDESC.DAT and then rename NEWUDS.DAT to
  424. USERDESC.DAT for the actions taken by this program to have effect in your
  425. UDS installation.
  426.  
  427. ===============================================================================
  428.  
  429. Various things to be aware of.
  430. ------------------------------
  431.  
  432. The program assumes two things to work properly: one, that the caller
  433. is calling at 8N1, and two, that the caller is either using VT100 or
  434. ANSI-BBS terminal emulation. The only use of ANSI/VT100 control sequences
  435. is to clear the screen. Both of these requirements are stated on the
  436. opening screen that the caller sees when he or she first enters the UDS.
  437. If this proves to be an inconvenient set of assumptions, I may be able
  438. to do something about it. I've planned for a while to allow the UDS to
  439. pick up the user's terminal type from Fido's CALLER.SYS record, but at
  440. this time there are no terminal types defined in the version of Fido
  441. that I am running (and that the UDS has been tested with), which is 12r.
  442.  
  443. Another thing to be aware of is that the user description itself is one
  444. long string and is written to the caller's terminal that way. If the
  445. caller's terminal program does not wrap lines longer than 80 characters
  446. on his or her screen, the caller will see the first 79 characters of the
  447. description followed by whatever is the last character of the description
  448. in column 80, as the characters above 80 will overwrite the last portion
  449. of the line. Some terminal programs may give other, less desireable
  450. results. You may want to tell your callers to turn on line wrapping in
  451. the help file you create for the UDS. If some nice sysop out there will
  452. netmail his or her help file to me, I will include it in a future release
  453. of the UDS.
  454.  
  455. The UDS attempts to handle the time the caller is online in the UDS
  456. correctly. There is at least one known exception, described below.
  457. When the caller first enters the UDS, the program checks the maximum
  458. times you have defined in FIDO.SYS for callers to be online. This includes
  459. both the time allowable per call and total per day. As the user remains
  460. in the UDS and time elapses, time is checked on a regular basis (and in
  461. more than one location in the code). The caller's time online so far today
  462. (as held in FIDO.SYS) is constantly updated, so that the caller can't
  463. "beat the system" by dropping carrier and calling back in to the BBS.
  464. At the conclusion of the user's online session, the time remaining on
  465. this call is given to Fido. This is done only upon successful completion
  466. since it doesn't matter under other circumstances.
  467.  
  468. The UDS gives callers time based on their privilege level. Since Fido
  469. doesn't store the time per day for each user, it's necessary to get the
  470. time per day and multiply it correctly for each user privilege level.
  471. The case that UDS doesn't handle correctly is Sysop access. Sysops will
  472. have their time set to the maximum user level time rather than unlimited
  473. time when they return to the BBS from the UDS. Under most circumstances
  474. this will not be a great inconvenience.
  475.  
  476. While the UDS does not test for or handle DESQview in any special way,
  477. it does do well-behaved video I/O and should be compatible with all
  478. known multitaskers. There are no direct video writes.
  479.  
  480. I hope you and your callers enjoy the UDS as much as I enjoyed writing
  481. it. Oh, there is no documentation on the operation of the UDS itself,
  482. since it is *supposed* to be self-explanatory. If this is not true,
  483. complain and I'll see what I can do about it. Better yet, include
  484. a help file or other documentation with your message, and if I use
  485. your version I'll be sure to give you credit for writing it (if you don't
  486. want to remain anonymous, that is.)
  487.  
  488. ===============================================================================
  489. "Caffeine-Free Software: Not Coffee-protected!"
  490. ===============================================================================
  491.  
  492.